7. Core API Reference | DSPConnection

An interface that manages Digital Signal Processor (DSP) Connections

Mix Properties:

• DSPConnection::setMix Sets the connection's volume scale.
• DSPConnection::getMix Retrieves the connection's volume scale.
• DSPConnection::setMixMatrix Sets a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).
• DSPConnection::getMixMatrix Retrieves a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

General:

• DSPConnection::getInput Retrieves the connection's input DSP unit.
• DSPConnection::getOutput Retrieves the connection's output DSP unit.
• DSPConnection::getType Retrieves the type of the connection between 2 DSP units.
• DSPConnection::setUserData Sets a user value associated with this object.
• DSPConnection::getUserData Retrieves a user value associated with this object.

• FMOD_DSPCONNECTION_TYPE List of connection types between 2 DSP nodes.

DSPConnection::getInput

Retrieves the connection's input DSP unit.

FMOD_RESULT DSPConnection::getInput(
  DSP **input
);

FMOD_RESULT FMOD_DSPConnection_GetInput(
  FMOD_DSPCONNECTION *dspconnection,
  FMOD_DSP **input
);

RESULT DSPConnection.getInput(
  out DSP input
);

DSPConnection.getInput(
  input
);

input Out

Input DSP unit. (DSP)

If DSP::addInput was just called, the connection might not be ready because the DSP system is still queued to be connected, and may need to wait several milliseconds for the next mix to occur. If so the function will return FMOD_ERR_NOTREADY and input will be null.

See Also: DSPConnection::getOutput, DSP::addInput

DSPConnection::getMix

Retrieves the connection's volume scale.

FMOD_RESULT DSPConnection::getMix(
  float *volume
);

FMOD_RESULT FMOD_DSPConnection_GetMix(
  FMOD_DSPCONNECTION *dspconnection,
  float *volume
);

RESULT DSPConnection.getMix(
  out float volume
);

DSPConnection.getMix(
  volume
);

volume Out

Volume scale applied to the input before being passed to the output. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.

• Units: Linear
• Range: (-inf, inf)
• Default: 1

See Also: DSPConnection::setMix

DSPConnection::getMixMatrix

Retrieves a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

FMOD_RESULT DSPConnection::getMixMatrix(
  float *matrix,
  int *outchannels,
  int *inchannels,
  int inchannel_hop = 0
);

FMOD_RESULT FMOD_DSPConnection_GetMixMatrix(
  FMOD_DSPCONNECTION *dspconnection,
  float *matrix,
  int *outchannels,
  int *inchannels,
  int inchannel_hop
);

RESULT DSPConnection.getMixMatrix(
  float[] matrix,
  out int outchannels,
  out int inchannels,
  int inchannel_hop = 0
);

DSPConnection.getMixMatrix(
  matrix,
  outchannels,
  inchannels,
  inchannel_hop
);

matrix OutOpt

Two dimensional array of volume levels in row-major order. Each row represents an output speaker, each column represents an input channel. Passing null or equivalent as the matrix allows querying of outchannels and inchannels.

• Units: Linear
• Range: (-inf, inf)

outchannels OutOpt

Number of valid output channels (rows) in matrix. Optional only when matrix is null or equivalent.

inchannels OutOpt

Number of valid input channels (columns) in matrix. Optional only when matrix is null or equivalent.

inchannel_hop Opt

Width (total number of columns) in destination matrix. Can be larger than inchannels to represent a smaller valid region inside a larger matrix.

A matrix element is referenced from the incoming matrix data as outchannel * inchannel_hop + inchannel.

See Also: DSPConnection::setMixMatrix

DSPConnection::getOutput

Retrieves the connection's output DSP unit.

FMOD_RESULT DSPConnection::getOutput(
  DSP **output
);

FMOD_RESULT FMOD_DSPConnection_GetOutput(
  FMOD_DSPCONNECTION *dspconnection,
  FMOD_DSP **output
);

RESULT DSPConnection.getOutput(
  out DSP output
);

DSPConnection.getOutput(
  output
);

output Out

Output DSP unit. (DSP)

If DSP::addInput was just called, the connection might not be ready because the DSP system is still queued to be connected, and may need to wait several milliseconds for the next mix to occur. If so the function will return FMOD_ERR_NOTREADY and output will be null.

See Also: DSPConnection::getInput, DSP::addInput

DSPConnection::getType

Retrieves the type of the connection between 2 DSP units.

FMOD_RESULT DSPConnection::getType(
  FMOD_DSPCONNECTION_TYPE *type
);

FMOD_RESULT FMOD_DSPConnection_GetType(
  FMOD_DSPCONNECTION *dspconnection,
  FMOD_DSPCONNECTION_TYPE *type
);

RESULT DSPConnection.getType(
  out DSPCONNECTION_TYPE type
);

DSPConnection.getType(
  type
);

type Out

Type of connection. (FMOD_DSPCONNECTION_TYPE)

DSPConnection::getUserData

Retrieves a user value associated with this object.

FMOD_RESULT DSPConnection::getUserData(
  void **userdata
);

FMOD_RESULT FMOD_DSPConnection_GetUserData(
  FMOD_DSPCONNECTION *dspconnection,
  void **userdata
);

RESULT DSPConnection.getUserData(
  out IntPtr userdata
);

DSPConnection.getUserData(
  userdata
);

userdata Out

User data set by calling DSPConnection::setUserData.

This function allows arbitrary user data to be retrieved from this object. See the User Data section of the glossary for an example of how to get and set user data.

DSPConnection::setMix

Sets the connection's volume scale.

FMOD_RESULT DSPConnection::setMix(
  float volume
);

FMOD_RESULT FMOD_DSPConnection_SetMix(
  FMOD_DSPCONNECTION *dspconnection,
  float volume
);

RESULT DSPConnection.setMix(
  float volume
);

DSPConnection.setMix(
  volume
);

volume

Volume scale applied to the input before being passed to the output. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.

• Units: Linear
• Range: (-inf, inf)
• Default: 1

See Also: DSPConnection::getMix, DSPConnection::setMixMatrix, DSPConnection::getMixMatrix

DSPConnection::setMixMatrix

Sets a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

FMOD_RESULT DSPConnection::setMixMatrix(
  float *matrix,
  int outchannels,
  int inchannels,
  int inchannel_hop = 0
);

FMOD_RESULT FMOD_DSPConnection_SetMixMatrix(
  FMOD_DSPCONNECTION *dspconnection,
  float *matrix,
  int outchannels,
  int inchannels,
  int inchannel_hop
);

RESULT DSPConnection.setMixMatrix(
  float[] matrix,
  int outchannels,
  int inchannels,
  int inchannel_hop = 0
);

DSPConnection.setMixMatrix(
  matrix,
  outchannels,
  inchannels,
  inchannel_hop
);

matrix Opt

Two dimensional array of volume levels in row-major order. Each row represents an output speaker, each column represents an input channel. Null or equivalent sets a 'default' matrix.

• Units: Linear
• Range: (-inf, inf)

outchannels

Number of output channels (rows) in matrix.

• Range: [0, FMOD_MAX_CHANNEL_WIDTH]

inchannels

Number of input channels (columns) in matrix.

• Range: [0, FMOD_MAX_CHANNEL_WIDTH]

inchannel_hop Opt

Width (total number of columns) in source matrix. Can be larger than inchannels to represent a smaller valid region inside a larger matrix.

• Range: [0, FMOD_MAX_CHANNEL_WIDTH]
• Default: inchannels

A matrix element is referenced from the incoming matrix data as outchannel * inchannel_hop + inchannel.

If null or equivalent is passed in via matrix a default upmix, downmix, or unit matrix will take its place. A unit matrix allows a signal to pass through unchanged.

Example 5.1 unit matrix:

1 0 0 0 0 0 
0 1 0 0 0 0 
0 0 1 0 0 0 
0 0 0 1 0 0 
0 0 0 0 1 0 
0 0 0 0 0 1

Matrix element values can be below 0 to invert a signal and above 1 to amplify the signal. Note that increasing the signal level too far may cause audible distortion.

See Also: DSPConnection::getMixMatrix

DSPConnection::setUserData

Sets a user value associated with this object.

FMOD_RESULT DSPConnection::setUserData(
  void *userdata
);

FMOD_RESULT FMOD_DSPConnection_SetUserData(
  FMOD_DSPCONNECTION *dspconnection,
  void *userdata
);

RESULT DSPConnection.setUserData(
  IntPtr userdata
);

DSPConnection.setUserData(
  userdata
);

userdata

Value stored on this object.

This function allows arbitrary user data to be attached to this object. See the User Data section of the glossary for an example of how to get and set user data.

See Also: DSPConnection::getUserData

FMOD_DSPCONNECTION_TYPE

List of connection types between 2 DSP nodes.

typedef enum FMOD_DSPCONNECTION_TYPE {
  FMOD_DSPCONNECTION_TYPE_STANDARD,
  FMOD_DSPCONNECTION_TYPE_SIDECHAIN,
  FMOD_DSPCONNECTION_TYPE_SEND,
  FMOD_DSPCONNECTION_TYPE_SEND_SIDECHAIN,
  FMOD_DSPCONNECTION_TYPE_MAX
} FMOD_DSPCONNECTION_TYPE;

enum DSPCONNECTION_TYPE
{
    STANDARD,
    SIDECHAIN,
    SEND,
    SEND_SIDECHAIN,
    MAX,
}

FMOD.DSPCONNECTION_TYPE_STANDARD
FMOD.DSPCONNECTION_TYPE_SIDECHAIN
FMOD.DSPCONNECTION_TYPE_SEND
FMOD.DSPCONNECTION_TYPE_SEND_SIDECHAIN
FMOD.DSPCONNECTION_TYPE_MAX

FMOD_DSPCONNECTION_TYPE_STANDARD

Default connection type. Audio is mixed from the input to the output DSP's audible buffer.

FMOD_DSPCONNECTION_TYPE_SIDECHAIN

Sidechain connection type. Audio is mixed from the input to the output DSP's sidechain buffer.

FMOD_DSPCONNECTION_TYPE_SEND

Send connection type. Audio is mixed from the input to the output DSP's audible buffer, but the input is NOT executed, only copied from. A standard connection or sidechain needs to make an input execute to generate data.

FMOD_DSPCONNECTION_TYPE_SEND_SIDECHAIN

Send sidechain connection type. Audio is mixed from the input to the output DSP's sidechain buffer, but the input is NOT executed, only copied from. A standard connection or sidechain needs to make an input execute to generate data.

FMOD_DSPCONNECTION_TYPE_MAX

Maximum number of DSP connection types supported.

FMOD_DSP_CONNECTION_TYPE_STANDARD

Default DSPConnection type. Audio is mixed from the input to the output DSP's audible buffer, meaning it will be part of the audible signal. A standard connection will execute its input DSP if it has not been executed before.

FMOD_DSP_CONNECTION_TYPE_SIDECHAIN

Sidechain DSPConnection type. Audio is mixed from the input to the output DSP's sidechain buffer, meaning it will NOT be part of the audible signal. A sidechain connection will execute its input DSP if it has not been executed before.

The purpose of the seperate sidechain buffer in a DSP, is so that the DSP effect can privately access for analysis purposes. An example of use in this case, could be a compressor which analyzes the signal, to control its own effect parameters (ie a compression level or gain).

For the effect developer, to accept sidechain data, the sidechain data will appear in the FMOD_DSP_STATE struct which is passed into the read callback of a DSP unit.

FMOD_DSP_STATE::sidechaindata and FMOD_DSP_STATE::sidechainchannels will hold the mixed result of any sidechain data flowing into it.

FMOD_DSP_CONNECTION_TYPE_SEND

Send DSPConnection type. Audio is mixed from the input to the output DSP's audible buffer, meaning it will be part of the audible signal. A send connection will NOT execute its input DSP if it has not been executed before.

A send connection will only read what exists at the input's buffer at the time of executing the output DSP unit (which can be considered the 'return')

FMOD_DSP_CONNECTION_TYPE_SEND_SIDECHAIN

Send sidechain DSPConnection type. Audio is mixed from the input to the output DSP's sidechain buffer, meaning it will NOT be part of the audible signal. A send sidechain connection will NOT execute its input DSP if it has not been executed before.

A send sidechain connection will only read what exists at the input's buffer at the time of executing the output DSP unit (which can be considered the 'sidechain return').

For the effect developer, to accept sidechain data, the sidechain data will appear in the FMOD_DSP_STATE struct which is passed into the read callback of a DSP unit.

FMOD_DSP_STATE::sidechaindata and FMOD_DSP_STATE::sidechainchannels will hold the mixed result of any sidechain data flowing into it.

See Also: DSP::addInput, DSPConnection::getType